Alemba API Cookbook - Recipes
Creating Calls
To create a call, you must choose a Call type, determine the url for the Call Create action, create a properly formatted Call object, serialize the object in JSON format and submit the object using HTTP POST.
Finally, the created Call may need to be submitted before it becomes visible to other system users.
Choosing a Call type
Each Call Type may be associated with its own extension fields.
These extension fields may not all be visible on all call types., so the recommended approach to choosing a call type is to derive this from ITIL IPK Tiers or Call Templates - if these are enabled.
IPK Statuses and Streams
In the Core application, users choose a type of call to log by choosing a screen set. This is often determined by selecting an IPK Status and then an IPK Stream, which in turn are mapped to a Screen Set. It is also possible to link Screen Set to a combination of IPK Status, IPK Stream add Call Problem Type .
These Call Type mappings are accessible through either api:v1/ipk-status-stream-to-type or api:v1/ipk-status-stream-type-to-type. Only one of these endpoints will be enabled. The enabled one will allow searching ,and the other will respond with HTTP Status code 404. To programmatically determine which to use, each endpoint can be queried using $options on the end of the query string.
Search the enabled call type mapping entity and choose one according to IPK Status, Stream and/or Call Problem Type.
The seach results from each include the usual hypermedia links, and also include "_actions".
For example
"IpkStatus": {
"Name": "Incident",
"_context": "api:v1/ipk-status/$metadata",
"_self": "api:v1/ipk-status/1"
},
"IpkStream": {
"Name": "Standard",
"_context": "api:v1/ipk-stream/$metadata",
"_self": "api:v1/ipk-stream/0"
},
"_context": "api:v1/ipk-status-stream-to-type/$metadata",
"_self": "api:v1/ipk-status-stream-to-type?$select=IpkStatus,IpkStream&$filter=(IpkStatus%3d%3d1%26%26IpkStream%3d%3d0%26%26InfraEntityType%3d%3d7)",
"_actions": {
"Create": [
{
"_self": "api:v1/incident/$Create",
"href": "api:v1/incident",
"description": "The resource that should be used to create a call of this type. IpkStatus and IpkStream from this result should be set in the new call."
}
]
}
}
Note that "_actions" contains a reference to a Create action. The Create action includes a hypermedia link to itself and a "href". This "href" is the link to use if you want to Create a Call of this type.
Note also the additional information in "description".
In this example, we would choose to create a call using api:v1/incident.
Call Templates
In the Self Service Portal, users choose a call template, which in turn is associated with a type of call. Call Templates can be searched using the api:v1/call-template resource and the results will contain references to the appropriate Create action in the hypermedia links for each search result.
{
"Ref": 96,
"Name": "Default",
"_context": "api:v1/call-template/$metadata",
"_self": "api:v1/call-template/96",
"_actions": {
"Create": [
{
"_self": "api:v1/call/$Create",
"href": "api:v1/call",
"description": "The resource that should be used to create a call of this type. The Template property in the new call should be set to the Ref of this result."
}
]
}
}
In this example, we would choose to create a call using api:v1/call.
When choosing a Call type using the API, either of these approaches can be used for any type of user, or you can define your own mechanism. For example, your user could choose from a list of Call types directly (instead of templates or IPK Tiers).
Creating a Call Object
Developers may choose to take a trial and error approach to call creation.
For example, submitting an empty Object will likely result in a validation error like the following:
{
"Message": "The request is invalid",
"Type": "FieldValidationException",
"Errors": {
"IpkStatus": [
"Required: IpkStatus must be set when Template is null"
],
"IpkStream": [
"Required: IpkStream must be set when Template is null"
],
"Partition": [
"Required"
]
}
}
The exact error is entirely dependent upon the configuration of the system.
Call Create Metadata
The metadata for the Call entity describes all of the actions that are available and all of the properties of that entity. Each action may also contain a description of the allowed inputs for that action.
The Call Create action is no exception and does define applicable inputs and the associated validation rules.
Some fields may be required or readonly depending upon the system configuration. This configuration is described in the action metadata and is validated by the server.
For example
{
"_context": "api:v1/call/$metadata",
"_self": "api:v1/call/$Create",
"href": "api:v1/call",
"methods": [
"POST"
],
"inputs": [
{
"property": "ConfigurationItem"
},
{
"property": "User"
},
{
"property": "Priority",
"readonly": true
},
{
"property": "Description",
"relations": [
{
"behaviors": [
{
"type": 11,
"scope": 1
}
],
"source": "Description",
"target": "DescriptionHtml"
}
]
},
{
"property": "DescriptionHtml",
"relations": [
{
"behaviors": [
{
"type": 14,
"scope": 1
}
],
"source": "DescriptionHtml",
"target": "Description"
}
]
},
{
"property": "Type"
},
{
"property": "Organization"
},
{
"property": "Template",
"relations": [
{
"behaviors": [
{
"type": 16,
"scope": 2
},
{
"type": 17,
"scope": 2
}
],
"source": "Template",
"target": "IpkStatus"
},
{
"behaviors": [
{
"type": 16,
"scope": 2
},
{
"type": 17,
"scope": 2
}
],
"source": "Template",
"target": "IpkStream"
},
{
"behaviors": [
{
"type": 16,
"scope": 2
}
],
"source": "Template",
"target": "Name"
}
]
},
{
"property": "IpkStatus",
"relations": [
{
"behaviors": [
{
"type": 14,
"scope": 2
}
],
"source": "IpkStatus",
"target": "IpkStream"
}
]
},
{
"property": "IpkStream",
"relations": [
{
"behaviors": [
{
"type": 14,
"scope": 2
}
],
"source": "IpkStream",
"target": "IpkStatus"
}
]
},
{
"property": "Partition",
"required": true,
"relations": [
{
"behaviors": [
{
"type": 15
}
],
"source": "Partition",
"target": "ConfigurationItem"
},
{
"behaviors": [
{
"type": 15
}
],
"source": "Partition",
"target": "User"
},
{
"behaviors": [
{
"type": 15
}
],
"source": "Partition",
"target": "Priority"
},
]
}
],
"description": "Create a new record of this type",
"status": "GA"
}The metadata for each action may include "_context", "_self", "href", "description" and "status"
It may also include "methods", which defines the HTTP Methods/Verbs that can be used for the action.
The action metadata may also define and array of "inputs"
Each input may include the following properties:
| property |
The path of the input value. This may be a reference to the name of a property for the current entity "_context" (see [[API Metadata]] or may be a dot separated path This defines the structure of the object that must be sent in the request body when the action is invoked. e.g $action.CallActionType describes the following JSON structure { "$action": { "CallActionType": value } }
When the "property" path does not refer to an entity property name, all other relevant property values will also be defined e.g. "type", "displayType", etc. |
| required | A boolean value indicating that the input is required. Omitted unless it is true |
| readonly | A boolean value indicating that the input is readonly. Omitted unless it is true |
| relations | An array of relationships between input fields Each relation includes "source" and "target" which reference "property" paths within the "inputs" array. Each relation will also include an array of "behaviours". These define validation level rules. The behaviors are used in server side validation and transformation rules and are provided so that the client can understand input requirements without needing to rely upon server side validation. |
Behaviours may include the following properties
| phase |
This indicates when the behavior will be applied. 1 indicates that the behavior will be applied after the record has been updated (but before it is committed to the database) 0 indicates that the behavior will be applied before, and therefore will apply to the input only. |
|
type |
This indicates the type of relation and may be one of the following 11 (CalculateHtmlTextIfNull): Indicates that the HTML text value of the target input should be set. When processed on the server. 12 (RequiredIfTrue): Indicates that the target input is required when the source input is true 13 (ZeroIfNotNull): Indicates that the target input must be set to zero when the source input has a value 14 (RequiredIfNotNull): Indicates that the target input is required when the source input has a value 15 (Dependency): Indicates that the target input is dependent upon the value of the source input. This typically applies to partitioned inputs. 16 (ReadonlyIfNotNull): Indicates that the target input is readonly when the source input has a value 17 (RequiredIfNull): Indicates that the target input is required when the source input does not have a value 18 (ReadonlyIfNull): Indicates that the target input is readonly when the source input does not have a value |
| scope |
This indicates where the behavior should be interpreted. 0 indicates that the behavior should be implemented by the client and will be ignored by the server 1 indicates that the behavior can be implemented by the client and will be implemented by the server 2 indicates that the behavior should be implemented by the client and will be implemented by the server |
Using the Call Create action metadata, we can easily determine which fields are required, and analyse the more complex relationships between fields.
For the example of creating a Call from a Template, the following ajax call could succeed
url: metadata.href.replace(/^api:/, "alemba.api/api"),
data: {
Template: 96
},
method: metadata.methods[0],
contentType: 'application/json',
headers: {
'Authorization': "Bearer " + access_token
}
});
Call Create Response
When successful, the Call Create action will respond with HTTP Status Code 201.
The response body will include the actual changes to the Call record and hypermedia links to the currently applicable actions.
For example
"ActualLogDate": "2017-01-23T12:12:41.0000000Z",
"Template": 96,
"Ref": 10056,
"_context": "api:v1/call/$metadata",
"_self": "api:v1/call/10056",
"_actions": {
"Submit": [
{
"_self": "api:v1/call/$Submit",
"href": "api:v1/call/10056/submit"
}
],
"Update": [
{
"_self": "api:v1/call/$Update",
"href": "api:v1/call/10056"
}
]
}
}The "_actions" property in the response indicates the actions which are applicable to the created Call in its current state. A Call will only be visible to the creator until it has been submitted, therefore if the "Submit" action is listed in the Create response, this action should be invoked before relinquishing responsibility for the Call.
Replicating behavior of Self Service
If a call is logged in Self Service, fixed rules are applied after saving, to populate certain fields. This has not been replicated in the API, as we will be making such rules configurable in the future. If you wish to replicate the current logic, you need to programmatically do so, following the rules below:
- If Location is not set, Location is set to the current User’s Location Ref (if they have one)
- If Organization is not set, Organization is set to the current User’s Organzation Ref (if they have one)
- If the Location is still not set, this is set to the first valid Location of: the selected User or Service or CI or Organization of the call.
- If the Organzation is still not set, this is set to the first valid Organzation from: the selected User or Service or CI of the call.
Impact of data on post-creation rules
Almost any property of a call may be used by IPK Workflow Rules, and each may have a different impact, according how the rules are set up in your system. The API user should be fully conversant with how these rules are configured, so as to achieve the desired assignment, notification and workflow creation.
Call creation checklist
To summarize, the actions to perform are as follows:
- For Users, select a Call Template (restricted by partition/security if active)
- For Analysts, select a Screen Set (and IPK Status, IPK Stream, Problem Type if so configured, restricted by partition/security if active)
- Then for both,
- Apply variable data
- Create Call
Creating Requests
The templates retrieved are subject to several security and configuration settings, including:
- partitioning Request Screen Sets and Workflow Templates
- Workflow Management Settings
- login's Workflow Management Role's Template Security settings
Calls and Requests – Determining Initial Assignment
In the WCF API, it is possible to specify the Officer and/or Group to which Calls and Requests are forwarded on creation. These are specified as parameters rather than properties to update. They are ignored if IPK or Workflow rules are in place to set this.
In the RESTful API, it is possible to set these values on the Defer action, rather than the Create, so API users should use both actions, one after the other, to achieve the same thing.
Calls and Requests – Recording Actions
In the WCF API, the transactions to create and update calls include the ability to record “Action and Solution” information, which is largely recorded an associated history record. In the RESTful API, this can be achieved using the Defer action. This may include some of the following parameters:
- $action.Description.Description
- $action.Description.DescriptionHtml
- $action.Description.Title
- $action.ActionType
Creating a Service Order
The items that need to be created for a valid service order are:
- Service Order
- Service Order Items
- A Call or Request per Service Order Item (if you want those items immediately submitted)
Required inputs are: one or more service actions and/or service bundles, and a quantity for each.
To create a new Service Order, a new service order record must first be created (api:v1/service-order/$create)
For each service action in the order:
A Service Order Item linked to the Service Order must be created (api:v1/service-order-item/$create) and a Call or Request must be created which is linked to the Service Order Item.
The type of Call or Request to create is indicated in the metadata links for each service action
Finally, the Service Order must be Submitted (using the Submit action), which will automatically calculate the Order Total and Submit the linked Tickets.
The new dynamic service bundle type is not supported in this version of the API.
The creation of a request will automatically create the necessary tasks and initiate the workflow.
Note that the entity called Order is used for transactions that are part of Asset Management, and is not used for Service Orders.
Closing Calls
The process of closing a call in Core is subject to a number of configurable rules, settings and privileges. Some of these are handled by the rules engine and will be automatically invoked after calling the Close method, others need to be considered by the API user in determining what to pass to the Close method, and whether to call additional methods.